<!--$Id: client.so,v 1.12 2003/10/18 19:16:07 bostic Exp $-->
<!--Copyright (c) 1997,2008 Oracle.  All rights reserved.-->
<!--See the file LICENSE for redistribution information.-->
<html>
<head>
<title>Berkeley DB Reference Guide: Client program</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<a name="2"><!--meow--></a>
<table width="100%"><tr valign=top>
<td><b><dl><dt>Berkeley DB Reference Guide:<dd>RPC Client/Server</dl></b></td>
<td align=right><a href="../rpc/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rpc/server.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
<p align=center><b>Client program</b></p>
<p>Changing a Berkeley DB application to remotely call a server program requires
only a few changes on the client side:</p>
<ol>
<p><li>The client application must create and use a Berkeley DB environment; that
is, it cannot simply call the <a href="../../api_c/db_class.html">db_create</a> function, but must
first call the <a href="../../api_c/env_class.html">db_env_create</a> function to create an environment
in which the database will live.
<p><li>The client application must call <a href="../../api_c/env_class.html">db_env_create</a> using the
<a href="../../api_c/env_class.html#DB_RPCCLIENT">DB_RPCCLIENT</a> flag.
<p><li>The client application must call the additional <a href="../../api_c/env_class.html">DB_ENV</a> method
<a href="../../api_c/env_set_rpc_server.html">DB_ENV-&gt;set_rpc_server</a> to specify the database server.  This call must
be made before opening the environment with the <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a>
call.
</ol>
<p>The client application provides a few pieces of information to Berkeley DB as
part of the <a href="../../api_c/env_set_rpc_server.html">DB_ENV-&gt;set_rpc_server</a> call:</p>
<ol>
<p><li>A client structure.  Applications wanting to control their own client
structures can pass one in, and Berkeley DB will use it to connect to the
server.  Most applications will not make use of this argument and should pass
in NULL.  If this argument is used, the hostname and client timeout
arguments are ignored.  Applications using this mechanism must
create their client structures using DB_RPC_SERVERPROG as the program
number and DB_RPC_SERVERVERS as the version number.
<p><li>The hostname of the server.  The hostname format is not specified by
Berkeley DB, but must be in a format acceptable to the local network support
-- specifically, the RPC clnt_create interface.
<p><li>The client
timeout.  This is the number of seconds the client will wait for the
server to respond to its requests.  A default is used if this value is
zero.
<p><li>The server timeout.  This is the number of seconds the server will allow
client resources to remain idle before releasing those resources.  The
resources this applies to are transactions and cursors because those
objects hold locks; and if a client dies, the server needs to release
those resources in a timely manner.  This value is really a hint to the
server because the server may choose to override this value with its
own.
</ol>
<p>The only other item of interest to the client is the home directory
that is given to the <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> call.
The server is started with a list of allowed home directories.
The client must use one of those names (where a name is the last
component of the home directory).  This allows the pathname structure
on the server to change without client applications needing to be
aware of it.</p>
<p>Once the <a href="../../api_c/env_set_rpc_server.html">DB_ENV-&gt;set_rpc_server</a> call has been made, the client is
connected to the server, and all subsequent Berkeley DB
operations will be forwarded to the server.  The client does not need to
be otherwise aware that it is using a database server rather than
accessing the database locally.</p>
<p>It is important to realize that the client portion of the Berkeley DB library
acts as a simple conduit, forwarding Berkeley DB interface arguments to the
server without interpretation.  This has two important implications.
First, all pathnames must be specified relative to the server.  For
example, the home directory and other configuration information passed
by the application when creating its environment or databases must be
pathnames for the server, not the client system.  In addition, because
there is no logical bundling of operations at the server, performance
is usually significantly less than when Berkeley DB is embedded within the
client's address space, even if the RPC is to a local address.</p>
<table width="100%"><tr><td><br></td><td align=right><a href="../rpc/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rpc/server.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
<p><font size=1>Copyright (c) 1996,2008 Oracle.  All rights reserved.</font>
</body>
</html>
